Skip to main content
Version: 1.0.0

downloadVariantJsonsHttps

Function Name: downloadVariantJsonsHttp

Author: Domenico Cerone Creation Date: 02/10/2025
Last Reviewer: Domenico Cerone

Trigger: HTTPS (onRequest)

Purpose: Manages the download of product data and automatic generation of Excel reports for optical products from the Safilo catalog. Processes SKUs with result='Orderable', downloads JSON data and images, generates Excel reports, and automatically sends quotation request emails to administrators.

Detailed Functionality​

This Firebase Function performs a comprehensive data processing workflow for product catalogs:

1. CATALOG DATA RETRIEVAL​

  • Receives catalog order ID from HTTP request
  • Retrieves document from 'CatalogOrders' Firestore collection
  • Utilizes Firebase Storage bucket 'arshades-7e18a.appspot.com'

2. SKU EXTRACTION​

  • Filters only elements with result = 'Orderable' (regardless of isSelected value)
  • Extracts SKU codes from filtered elements
  • Removes duplicates to avoid multiple processing

3. BATCH PROCESSING​

  • Processes SKUs in batches of 20 elements to optimize performance
  • Each batch is processed in parallel for maximum efficiency
  • Implements 200ms delay between API calls to avoid overload

4. JSON DOWNLOAD AND MANAGEMENT​

  • NEW API: https://commportal-api.safilo.com/damAPI/damitems/AUTH.../spaarkly.getModels?sizeCode={sku}
  • Checks existence in Storage: ARS_Library_Product_Data/{skuCode}/json/{skuCode}.json
  • If not exists: downloads, saves temporarily, uploads to Storage with UUID token
  • If exists: uses existing file to extract image parameters

5. IMAGE DOWNLOAD AND OPTIMIZATION​

  • Extracts modelCode, colorCode, lensCode from JSON for each SKU
  • Downloads 2 images (detail=00 frontal, detail=04 lateral)
  • API: https://safilo-pd-cdn002.safilo.com/damapi/damimage/public/sfcc.getimagenofb
  • Optimizes images: resizes to 120x120px, JPEG quality 90%, progressive format
  • Fallback: Sharp → Jimp → original buffer
  • Storage: ARS_Library_Product_Data/{skuCode}/thumbnail/{modelCode}_{colorCode}_{lensCode}_{detail}.jpg

6. AUTOMATIC EXCEL REPORT GENERATION​

  • Always generates Excel report automatically at the end of processing
  • Includes: skuCode, Style Description, frontal image (00), lateral image (04)
  • ENHANCED IMAGE HANDLING:
    • Downloads images from URLs (Firebase Storage or API) into memory for each call
    • Uses downloadImageToBuffer function to get image buffer
    • Implements complete validity checks: URL, status code, content-type, buffer size
    • Detailed logging to track every phase of download and conversion
    • Robust error handling with complete diagnostic information
    • Even when images are already present in Storage (skipped), they are downloaded again for Excel inclusion
  • Optimizes images with Sharp/Jimp (120x120px, JPEG 90%)
  • Creates Excel with ExcelJS: 4 columns (SKU, Description, Img00, Img04)
  • Cell dimensions: width 18-30 units, height 75 points
  • PERFECT IMAGE CENTERING: Uses exact coordinates for perfect centering
  • Bold headers, fixed row height
  • Saves Excel to Storage: Orders/{orderId}/Orders-orderid-report.xlsx
  • Generates UUID token for public access
  • AUTOMATIC CLEANUP: Deletes all temporary files (Excel and images) after processing

7. ENHANCED API ERROR HANDLING​

  • NEW LOGIC: Image errors no longer cause complete order failure
  • Detects errors during API calls (JSON and images)
  • JSON ERRORS: Still cause order failure (status "error") - these are critical
  • IMAGE ERRORS: Only cause individual SKU failure, order continues processing
  • Adds "status" field with value "Failed - API json/images" ONLY to individual SKUs with errors
  • Order status remains "processing_addition" and updates to "completed" at the end
  • SPECIFIC HTTP 410 (Gone) HANDLING:
    • Error 410 indicates image no longer available on Safilo server
    • Not considered critical system error, only resource unavailability
    • Processing continues normally for other SKUs
    • Statistics distinguish between technical errors (failed) and unavailable images (unavailable)
    • Excel report is still generated with empty cells for unavailable images
  • ERROR TYPES TRACKED:
    • JSON_API_ERROR: Critical errors during JSON download (causes order failure)
    • IMAGE_API_ERROR: Non-critical image download errors (individual SKU only)
    • IMAGE_NOT_AVAILABLE: Images no longer available (HTTP 410)
    • IMAGE_PROCESSING_ERROR: Non-critical image processing errors
    • MISSING_IMAGE_PARAMS: Missing image parameters in JSON data (non-critical)
    • BATCH_PROCESSING_ERROR: Errors during batch processing
    • EXCEL_GENERATION_ERROR: Errors during Excel report generation
    • ORDER_UPDATE_ERROR: Errors during order update
    • GENERAL_ERROR: Uncategorized general errors

8. AUTOMATIC QUOTATION REQUEST EMAIL​

  • ENHANCED: Automatically sends quotation request email when Excel report is generated successfully
  • SENDING CONDITIONS: Email is sent in ALL these cases:
    • Successful processing (status "completed") AND Excel generated
    • Processing completed with image errors (status "completed") AND Excel generated
    • Processing failed with critical JSON errors (status "error") BUT Excel still generated
    • General errors during processing BUT Excel generated before error
  • NO EMAIL SENT: If Excel is not generated (e.g., no data, critical errors)
  • TWO DISTINCT EMAILS SENT:
    • Administrator email:
      • Template key: 13ef.8598f19fbcc5adb.k1.e8a28620-50ea-11f0-9c4e-dad70ff08860.197a19bc782
      • Recipients: ALL users with role='Admin' from Profiles collection
      • Merge data: formatted timestamp data and full name of ordering user
      • Attachment: Excel file downloaded from Storage URL and converted to base64
    • User confirmation email:
      • Template key: 13ef.8598f19fbcc5adb.k1.9337a850-5e23-11f0-9e15-dad70ff08860.197f8418755
      • Recipient: user who made the request (profile field from CatalogOrders)
      • Merge data: full user name (e.g., "Michele Telesca") or email if name unavailable
      • Message: "Hello {{profile}}, Request for quotation sent successfully!"
      • Sent immediately after admin email to confirm request to user
      • NO attachments, only confirmation of successful request
  • Uses sendQuotationRequestEmailHttp function for ZeptoMail sending
  • Robust error handling: If email sending fails, it's logged but doesn't interrupt process
  • No admin found: Email not sent if no administrators found (NO_ADMIN_FOUND error)
  • Detailed logging: Tracks every phase of email sending and administrator count

9. EXCEL REPORT URL SAVING IN CATALOGORDERS​

  • NEW FEATURE: When Excel report is generated successfully, the system automatically saves the file information directly in the CatalogOrders document on Firestore
  • Field added to document:
    • excelReportUrl: Complete public URL for direct Excel file download
    • excelReportFileName: Name of the generated Excel file
  • Saving occurs in ALL cases:
    • Successful processing (along with status "completed")
    • Processing completed with image errors (along with status "completed")
    • Processing failed with critical JSON errors (along with status "error")
    • General errors during processing (if Excel was generated before error)
  • Benefits:
    • Frontend can easily retrieve the report link directly from the order document
    • No need to reconstruct the URL
    • Link remains valid and accessible even after processing completion
    • Consistent data storage for future reference

Technical Features​

  • TIMEOUT: 540 seconds (9 minutes) for long processing
  • MEMORY: 1GiB to handle images and Excel files
  • REGION: europe-central2 for optimal performance
  • CORS: Enabled for frontend calls
  • ERROR HANDLING: Detailed logging, robust fallbacks, response with errorDescription
  • OPTIMIZATION: Parallel calls, intelligent cache, batch processing
  • SECURITY: UUID tokens for controlled file access
  • FORMAT: Excel XLSX with embedded images, professional layout

Storage Structure​

ARS_Library_Product_Data/
├── {skuCode}/
│   ├── json/
│   │   └── {skuCode}.json
│   └── thumbnail/
│       ├── {modelCode}_{colorCode}_{lensCode}_00.jpg
│       └── {modelCode}_{colorCode}_{lensCode}_04.jpg
└── Orders/
    └── {orderId}/
        └── Orders-orderid-report.xlsx

Input (Payload):​

{
  "orderId": "xq02X2a6CEFVoQtZd5Pa"
}

Parameters:

  • orderId (string, required): ID of the catalog order document in the 'CatalogOrders' collection

Output (Success):​

{
  "success": true,
  "message": "Processing completed: 5 new JSONs, 2 existing JSONs, 0 failed. Images: 8 new, 4 existing, 2 failed. 1 images not available on server (HTTP 410).",
  "stats": {
    "totalItems": 7,
    "processedItems": 7,
    "json": {
      "new": 5,
      "skipped": 2,
      "failed": 0
    },
    "images": {
      "new": 8,
      "skipped": 4,
      "failed": 2,
      "unavailable": 1
    },
    "hasApiError": false,
    "skusWithCriticalErrors": 0
  },
  "excelReport": {
    "fileName": "Orders-xq02X2a6CEFVoQtZd5Pa-report.xlsx",
    "downloadUrl": "https://firebasestorage.googleapis.com/v0/b/arshades-7e18a.appspot.com/o/Orders%2Fxq02X2a6CEFVoQtZd5Pa%2FOrders-xq02X2a6CEFVoQtZd5Pa-report.xlsx?alt=media&token=uuid-token",
    "token": "uuid-token"
  }
}

Response Properties:

  • success (boolean): Indicates if the operation was completed successfully
  • message (string): Descriptive message of the processing results
  • stats (object): Detailed statistics of processed items
    • totalItems (number): Total number of SKUs to process
    • processedItems (number): Number of SKUs actually processed
    • json (object): JSON download statistics (new, skipped, failed)
    • images (object): Image download statistics (new, skipped, failed, unavailable)
    • hasApiError (boolean): Indicates if there were critical API errors
    • skusWithCriticalErrors (number): Number of SKUs with critical errors
    • skusWithImageErrors (number): Number of SKUs with image errors (non-critical)
  • hasApiError (boolean): Global flag indicating if there were any API errors
  • errorDescription (string|null): General description of errors if any occurred
  • errorDetails (array): Array with specific error details for each error type
  • excelReport (object): Excel report information
    • fileName (string): Name of the generated Excel file
    • downloadUrl (string): Public URL for Excel file download
    • token (string): UUID token for file access

This output is returned in the HTTP response (Postman, browser, curl).

Testing​

URL (if HTTPS): http://127.0.0.1:5001/arshadesstaging/europe-central2/downloadVariantJsonsHttp

Test with Emulator:

  1. Start the Firebase emulator: firebase emulators:start --only functions
  2. Ensure you're using Node.js version 20: nvm use 20
  3. Test with curl:
curl -X POST "http://127.0.0.1:5001/arshadesstaging/europe-central2/downloadVariantJsonsHttp" \
-H "Content-Type: application/json" \
-d '{"orderId": "xq02X2a6CEFVoQtZd5Pa"}'

Postman Testing:

Deploy Command:​

firebase deploy --only functions:downloadVariantJsonsHttp

Production URL:​

downloadVariantJsonsHttp: https://europe-central2-arshades-7e18a.cloudfunctions.net/downloadVariantJsonsHttp